home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / percnt.zip / CUSTCTRL.TXT < prev    next >
Text File  |  1991-11-10  |  12KB  |  243 lines
  1.                   Custom Control Library Documentation
  2.  
  3. This file contains information useful to you if you intend to use the
  4. file CtrlDLL.DLL and the Percent Complete control included in it in your
  5. own programs.  You should read file this before you use the code.  If
  6. you use this code for any of your own programs and find any bugs in it,
  7. please let me know.
  8.  
  9. FILES IN THE ARCHIVE
  10. ====================
  11.  
  12. The following files should have been included in the archive when you
  13. downloaded it:
  14.  
  15. CUSTCTRL.TXT                             This file.
  16. PERCENT  BMP      406  11-09-91   9:40a  Bitmap for RW tool bar
  17. PERCENT  CUR      326  11-09-91  10:23a  Cursor for RW
  18. CTRLCOMM INC     1133  11-10-91   7:35p  Include file for RW & programs
  19. CTLDLLIM PAS      126   9-15-91   6:40p  Unit to use with TESTIT.PAS
  20. CTRLCOMM PAS     1504  11-09-91  11:59a  DLL common declarations unit
  21. CTRLDLGS PAS     3193  11-10-91  11:28p  Control style dialog unit
  22. CTRLDLL  PAS    13761  11-10-91  11:28p  Main DLL source file
  23. CTRLFLAG PAS     1514  11-10-91  11:30p  Control flag proc unit
  24. CTRLINFO PAS     2874  11-10-91  11:28p  Control information unit
  25. CTRLINIT PAS     3833  11-10-91  11:28p  DLL initialization unit
  26. CUSTCNTL PAS     2248  11-10-91  11:29p  Custom Control definitions
  27. PERCENTC PAS     1891  11-10-91   9:52p  WObjects compatible unit
  28. TESTIT   PAS     7919  11-07-91   9:10p  Test program for the % control
  29. WNDFNPER PAS    16477  11-10-91  11:29p  Percent control window proc
  30. CTRLDLL  RC      2334  11-10-91   7:35p  Resource script for DLL
  31. TESTIT   RC      1766  11-07-91   7:26p  Resource script for test prog.
  32.  
  33.  
  34. INSTALLING THE SOURCE CODE
  35. ==========================
  36.  
  37. After unzipping the archive, should place all the source files for the
  38. DLL into the same directory.  Development was done in the directory
  39. C:\PROGRAMS\UNITS, but you may place the code in any directory that
  40. suits your working habits.  Just be sure that TPW is configured properly
  41. to find and place all .PAS, .INC, .TPU, and .DLL files.
  42.  
  43. COMPILING THE LIBRARY
  44. =====================
  45.  
  46. When you compile the library, be sure to MAKE or BUILD the file
  47. CTRLDLL.PAS within the TPW Integrated Development Environment.  The
  48. compiler will then automatically compile all source files and build a
  49. .DLL file.  Once this is done, you can now write programs that use the
  50. control class defined in the DLL.
  51.  
  52. This code is intended for use with Borland International's Turbo Pascal
  53. for Windows compiler.  It was specifically written for use with the
  54. version 1.0 product.  Compatibility with future versions of the compiler
  55. is not guaranteed by the author.  Attempting to compile this code for
  56. any other environment is not recommended.
  57.  
  58. Make sure you place the compiled DLL file in a directory on your path.
  59. This will make it easier for a program that uses the DLL to find it and
  60. load it.  Remember, if Windows can't find the DLL file, it will prompt
  61. you to place a disk in A:, which probably won't be of much help!
  62.  
  63. USING THE PERCENT COMPLETE CONTROL
  64. ==================================
  65.  
  66. The discussion of using the Percent Complete Control is divided into
  67. three parts, as follows:
  68.  
  69. 1. Control styles defined & their effects on an instance
  70. 2. User interface considerations
  71. 3. Programming considerations
  72.  
  73.  
  74. 1. Control Styles
  75. -----------------
  76.  
  77. A Percent Complete Control is composed of several parts.  The control
  78. draws them from the top down.  The parts, in order from top to bottom,
  79. are:  an optional caption, a bar showing the current percent setting of
  80. the control, an optional digital display of the current percent setting
  81. in the middle of the bar, optional tickmarks in either 10%, 25%, or 50%
  82. gradations, and an optional axis labeling each of the tickmarks.
  83.  
  84. The control defines 5 different style identifiers, which may be used in
  85. various combinations.  These identifiers and their effects are:
  86.  
  87. Pct_10Grads     Draws percentage tickmarks at 10% gradations
  88. Pct_25Grads     Draws percentage tickmarks at 25% gradations
  89. Pct_50Grads     Draws percentage tickmarks at 50% gradations
  90. Pct_DrawAxis    Draws an axis under the tickmarks.
  91. Pct_DrawPct     Draws the percentage as "x^" in the center of the bar
  92.  
  93. Note that Pct_10Grads, Pct_25Grads, and Pct_50Grads are all mutually
  94. exlusive styles.  You can use one or none of these identifiers in the
  95. window style of an instance of the control.  Not using any of them
  96. causes the control to not draw any tickmarks, while using one of them
  97. causes it to draw tick marks in the gradations indicated.
  98.  
  99. You should also not use Pct_DrawAxis if you do not also use one of the
  100. tickmark styles.  It makes no sense to draw an axis if you don't also
  101. draw tickmarks!
  102.  
  103. Finally, Pct_DrawPct may be freely mixed with any of the other styles.
  104.  
  105. The control always has a percentage complete bar, whose height is
  106. dependent on whether or not there is a caption, and on which styles have
  107. been set for the control.  The following paragraphs detail the effects
  108. of certain combinations on the height of the bar.
  109.  
  110. Specifying a caption:  Specifying a caption causes the control to leave
  111.                        space above it for the caption plus some white
  112.                        space to separate the caption from the top of the
  113.                        control's area & from the percent complete bar.
  114.  
  115. No styles specified :  Not specifying any of the styles will cause the
  116.                        control to draw itself as a solid bar across the
  117.                        entire width of the control.  The bar's height
  118.                        will be the height of the control minus any space
  119.                        required by the control's caption and any white
  120.                        space needed to separate it from the bar.
  121.  
  122. Pct_XXGrads:           Specifying one of these three styles causes the
  123.                        control to leave room beneath the bar for
  124.                        tickmarks four dialog units high.
  125.  
  126. Pct_DrawAxis:          Specifying this style causes the control to leave
  127.                        additional room beneath the control to draw an
  128.                        axis 8 dialog units high, plus some additional
  129.                        white space to separate the axis text from the
  130.                        bottom of the control's space.  The bar's width
  131.                        is decreased by 20 dialog units to allow the axis
  132.                        to fit within the control's space.
  133.  
  134. Pct_DrawPct:           Specifying this style has no effect on the height
  135.                        of the percentage complete bar.
  136.  
  137. The following paragraphs briefly describe the algorithms used by the
  138. control when it draws itself on the screen.
  139.  
  140. The control responds to the wm_EraseBackground message.  When this
  141. message is processed, the control sends the wm_CtlColor message to its
  142. parent.  This allows your dialog boxes to exert control over the
  143. appearance of the control by specifying the brush the control will use
  144. to erase its background.  In addition, if the control's background is
  145. not to use the stock white brush, the control will draw a 3D depression
  146. around itself before it draws itself.  This allows the control to be
  147. used BorDlg dialogs without using a group shade box to enclose the
  148. control.
  149.  
  150. The appearance of the percentage bar is modeled after that of the same
  151. type of control used in the Norton Desktop for Windows.  When it is
  152. drawn, the bar has a 3D button-like appearance.  The global system
  153. colors COLOR_BUTTON, COLOR_WINDOW, & COLOR_BTNSHADOW are used to
  154. determine the face color of the button and the colors to use for the
  155. button shadow & highlight.  At 0 percent, the control appears to be a
  156. trough in the dialog display; as the percentage approaches 100%, the bar
  157. comes closer to appearing as a complete button.
  158.  
  159. Any caption, percentage complete digits, tickmarks, and axis labels are
  160. drawn using the pen currently selected in the window's DC.  That is, the
  161. pen that's specified in the DC when the BeginPaint procedure returns.  I
  162. believe this pen may be set by the control's parent, which is why the
  163. control does not change the pen at this time.
  164.  
  165.  
  166. 2. User Interface
  167. -----------------
  168.  
  169. The Percent Complete Control is a passive control window class that is
  170. intended to only display data.  As such, the control does not respond to
  171. any mouse or keyboard messages, and should never receive the input
  172. focus.
  173.  
  174.  
  175. 3. Programming Considerations
  176. -----------------------------
  177.  
  178. When an instance of the control is created, it will show 0% complete.
  179. Since the control does not accept keyboard or mouse input, a problem
  180. presents itself.  That is, how do you change the percentage displayed?
  181.  
  182. To change the percentage value currently displayed by the control, you
  183. use one of 4 different messages the control recognizes.  These messages
  184. and their meanings are:
  185.  
  186. pcm_ResetPercent:       Reset percentage displayed to 0.
  187. pcm_AddPercent:         Add wParam (signed) percent to the value displayed.
  188. pcm_GetPercent:         Control returns value displayed.
  189. pcm_SetPercent:         Set value displayed to an arbitrary value.
  190.  
  191. Note that the percentage displayed may never be below 0 or above 100.
  192. Also, the percentage is stored as an integer value, so the control is
  193. not capable of displaying 50.5% complete, as an example.
  194.  
  195. Two units are provided in the archive which enable your programs to use
  196. the percentage control.  One is in the file PERCENTC.PAS, and the other
  197. is in CTRLDLLIM.PAS.  Both of these files are provided for two different
  198. purposes, as explained below.
  199.  
  200. Using CTRLDLLIM.PAS
  201. -------------------
  202.  
  203. The CTRLDLLIM.PAS unit is intended to be used by programs like RW that
  204. must import the DLL and gain direct access to the routines in the DLL.
  205. Note that this is probably not very useful in most circumstances, since
  206. RW & the MS SDK program DIALOG.EXE don't need or use this interface!  It
  207. is provided to allow TESTIT.EXE to run, and can be used if you find you
  208. need it for a program.
  209.  
  210. Note that the CenterPopup routine exported by the DLL may come in handy
  211. in your own programs.  It is intended to be used by popup windows, such
  212. as dialog boxes, either modal or modeless.  The procedure takes the
  213. handle to a window and a handle to that window's device context (DC) as
  214. parameters.  The routine automatically centers the dialog box either
  215. within the borders of its parent/owner window (if the parent is big
  216. enough to completely contain the popup window), or within the screen in
  217. the event the parent/owner window does not completely contain the popup.
  218.  
  219. The code included in CenterPopup is a Pascal translation of a C routine
  220. written by Kevin P. Welch & included in an article he wrote in the July
  221. 1990 issue of MSJ.
  222.  
  223. Using PERCENTC.PAS
  224. ------------------
  225.  
  226. The PERCENTC.PAS unit implements an ObjectWindows class called
  227. TPercentCtrl.  This control is a descendant of TControl and allows any
  228. OWL program to use this control.  The class defines methods
  229. corresponding to the 4 custom messages the control implements.
  230.  
  231.  
  232. COPYRIGHT INFORMATION
  233. =====================
  234.  
  235. All code in this unit is the property of Anthony M. Vitabile, Copyright
  236. 1991.  You may use this code in your own programs provided you include
  237. the above copyright notice.
  238.  
  239. Please note that the code included in the files that make up the DLL is
  240. provided "as-is."  I'll gladly allow anyone to use this code, but I
  241. don't make any warranties or guarantees about its fitness for anything.
  242.  
  243.